Criando a primeira aplicação Yii
================================

Para lhe dar uma experiência inicial com o Yii, descrevemos nesta seção como criar 
a sua primeira aplicação em Yii. Nos vamos usar o `yiic` (ferramenta de linha de comando)
para criar uma nova aplicação em Yii e `Gii` (poderoso gerador de código na web)
para automatizar a criação de código para determinadas tarefas. Por conveniência,
assumiremos que `YiiRoot` é o diretório onde o Yii está instalado e `WebRoot` é
o diretório raíz do servidor Web.

Execute o `yiic` pela linha de comando, como no exemplo a seguir:

~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive
~~~

> Note|Nota: Quando executamos o `yiic` no Mac OS, Linux ou Unix, devemos 
> alterar a permissão do arquivo `yiic` para torna-lo executável.
> Como forma alternativa, você pode executa-lo da seguinte maneira:
>
> ~~~
> % cd WebRoot
> % php YiiRoot/framework/yiic.php webapp testdrive
> ~~~

Esse comando irá criar um esqueleto de uma aplicação Yii no diretório `WebRoot/testdrive`. 
A aplicação tem um estrutura de diretórios que é a necessária para a maioria das 
aplicações feitas no Yii.

Sem ter escrito uma única linha de código, já podemos testar nossa primeira aplicação Yii, 
acessando a seguinte URL:

~~~
http://nomedoservidor/testdrive/index.php
~~~

Como podemos ver, a aplicação tem quatro páginas: a página inicial, a página 
sobre, a página de contato e a página de login. A página principal mostra algumas
informações sobre a aplicação, como o login do usuário ativo, a página de contato
exibe um formulário de contato que os usuários podem preencher 
e enviar suas mensagens, a página de login permite que os usuários se autentiquem antes de acessar 
o conteúdo privilegiado. Veja as imagens a seguir para mais detalhes:


![Página Principal](first-app1.png)

![Página de Contato](first-app2.png)

![Página de Contato com erros de entrada](first-app3.png)

![Página de Contato com emissão bem sucedida](first-app4.png)

![Página de Login](first-app5.png)


A listagem seguinte mostra a estrutura de diretórios da nossa aplicação.
Por favor, veja as [Convenções](/doc/guide/basics.convention#directory) para
obter explicações detalhadas sobre essa estrutura.

~~~
testdrive/
   index.php                 Script de entrada da aplicação Web
   index-test.php            Script de entrada para os testes funcionais
   assets/                   Contém arquivos de recurso publicados
   css/                      Contém arquivos CSS
   images/                   Contém arquivos de imagem
   themes/                   Contém temas da aplicação
   protected/                Contém arquivos protegidos da aplicação
      yiic                   Script de linha de comando yiic
      yiic.bat               Script de linha de comando yiic para o Windows
      yiic.php               Script PHP de linha de comando yiic 
      commands/              Contém comandos 'yiic' customizados
         shell/              Contém comandos 'yiic shell' customizados
      components/            Contém componentes reutilizáveis do usuário
         Controller.php      A classe padrão para todos os controles
         UserIdentity.php    A classe 'UserIdentity' usada nas autenticações
      config/                Contém arquivos de configurações
         console.php         Configuração da aplicação console
         main.php            Configuração da aplicação Web
         text.php            Configuração para os testes funcionais
      controllers/           Contém arquivos das classes de controle
         SiteController.php  Classes de controle padrão
      data/                  Contém exemplos de banco de dados
         schema.mysql.sql    Esquemas de BD com o banco de amostra em MySQL
         schema.sqlite.sql   Esquemas de BD com o banco de amostra em SQLite
         testdrive.db        Arquivo do banco de dados de amostra do SQLite
      extensions/            Contém extensões de terceiros
      messages/              Contém mensagens traduzidas
      models/                Contém arquivos das classes de modelo
         LoginForm.php       Modelo do formulário para a ação 'login'
         ContactForm.php     Modelo do formulário para a ação 'contact'
      runtime/               Contém arquivos gerados temporariamente
      tests/                 Contém scripts para os testes
      views/                 Contém arquivos de visão dos controles e layouts
         layouts/            Contém arquivos de visão do layout
            main.php         O layout padrão para todas as páginas
            column1.php      O layout para páginas com coluna única
            column2.php      O layout para páginas com duas colunas
         site/               Contém arquivos de visão para o controle 'site'
            pages/           Contém páginas "estática"
               about.php     A visão para a página "about"
            contact.php      Visão para a ação 'contact'
            error.php      	 Visão para a ação 'error' (exibindo erros externos)
            index.php        Visão para a ação 'index' 
            login.php        Visão para a ação 'login' 
~~~

O gerador de aplicação descrito acima também suporta a criação de arquivos necessários
pelo sistema de controle de versão Git. O comando a seguir deveria criar os arquivos:
`.gitignore` (por exemplo, o conteúdo dos diretórios `assets` e `runtime` não devem
ser rastreado) e `.gitkeep` (força o rastreamento de diretórios inicialmente vazios
mas importante).

~~~
% YiiRoot/framework/yiic webapp WebRoot/testdrive git
~~~

Outro VCS(sistema de controle de versão) suportado é o Mercurial: passe o valor hg
como terceiro parâmetro se você estiver usando este VCS. Este recurso está 
disponível desde a versão 1.1.11.

Conectando ao Banco de Dados
----------------------------

A maioria das aplicações Web são auxiliadas com o uso de banco de dados.
Nossa aplicação de test-drive não é uma exceção. Para usar um banco de dados,
primeiro precisamos dizer à aplicação como se conectar a ele. Isto é feito
alterando o arquivo de configuração `WebRoot/testdrive/protected/config/main.php`, 
como mostrado abaixo:

~~~
[php]
return array(
	......
	'components'=>array(
		......
		'db'=>array(
			'connectionString'=>'sqlite:protected/data/testdrive.db',
		),
	),
	......
);
~~~

Acima, nós adicionamos uma entrada para `db` ao array `components`, que instrui a
aplicação para se conectar ao banco de dados SQLite `WebRoot/testdrive/protected/data/testdrive.db` 
quando for preciso. Nota-se que o banco de dados SQLite já está incluído no esqueleto da
aplicação que acabou de ser gerada. O banco de dados contém apenas uma única tabela chamada `tbl_user`:

~~~
[sql]
CREATE TABLE tbl_user (
	id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
	username VARCHAR(128) NOT NULL,
	password VARCHAR(128) NOT NULL,
	email VARCHAR(128) NOT NULL
);
~~~

Se você quiser tentar um banco de dados MySQL, você pode usar o arquivo de esquema 
`WebRoot/testdrive/protected/data/schema.mysql.sql` para criar o banco de dados.

> Note|Nota: Para utilizar os recursos de banco de dados do Yii, precisamos ativar
a extensão PDO do PHP e a extensão de driver PDO específico. Para a aplicação test-drive,
as extensões `php_pdo` e `php_pdo_sqlite` deverão estar habilitadas.


Implementando operações do tipo CRUD
------------------------------------

Agora começa a parte divertida. Iremos implementar operações CRUD (create, read,
update and delete) quer realizará inserções, leituras, edições e deleções na 
tabela `tbl_user` que acabamos de criar. Este tipo de operação é frequetemente necessário
em aplicações reais. Em vez de se dar ao trabalho de escrever o código real, vamos
usar Gii - um poderoso gerador de código baseado na web.

> Info|Info: Gii está disponível desde a versão 1.1.2. Antes disso, podemos usar a 
ferramenta mencionada `yiic` para realizar a mesma funcionalidade. Para mais detalhes,
consulte a [Geração de código utilizando a ferramenta de linha de comando](/doc/guide/quickstart.first-app-yiic).


### Configuring Gii

Para poder usar Gii, primeiro precisamos editar o arquivo `WebRoot/testdrive/protected/config/main.php`,
que é conhecido como o arquivo de [configuração da aplicação](/doc/guide/basics.application#application-configuration).

~~~
[php]
return array(
	......
	'import'=>array(
		'application.models.*',
		'application.components.*',
	),

	'modules'=>array(
		'gii'=>array(
			'class'=>'system.gii.GiiModule',
			'password'=>'pick up a password here',
		),
	),
);
~~~

Então, visite a URL `http://nomedoservidor/testdrive/index.php?r=gii`. 
Vai ser solicitada uma senha, que deve ser a mesma que você acabou de entrar na configuração da aplicação.

### Gerando o Modelo User

Após o login, clique no link `Model Generator`. Isto nos levará para a página modelo de geração,

![Gerador de Modelo](gii-model.png)

No campo `Table Name`, digite `tbl_user`. No campo `Model Class`, digite `User`. Então pressione o botão `Preview`.
Isso vai nos mostrar o novo arquivo de código a ser gerado. Agora pressione o botão `Generate`.
Um novo arquivo chamado `User.php` será criado em `protected/models`. Como descreveremos mais adiante
neste guia, esta classe modelo `User` nos permite falar com a tabela de banco de dados `tbl_user` 
de forma orientada a objetos.

### Gerando o código CRUD

Depois de criar o arquivo da classe do modelo, nos iremos gerar o código que implementa as operações CRUD
sobre os dados do usuário. Escolhemos o Gerador de CRUD no Gii, como mostrado a seguir.

![Gerador CRUD](gii-crud.png)

No campo `Model Class`, digite `User`. No campo `Controller ID`, digite `user` (em minúsculo). Agora
pressione o botão `Preview` seguido do botão `Generate`. Nós finalizamos a geração de código CRUD.

### Acessando as páginas do CRUD

Vamos verificar o nosso trabalho pela seguinte URL:

~~~
http://nomedoservidor/testdrive/index.php?r=user
~~~

Isto irá exibir uma lista dos usuários registrados na tabela `tbl_user`.

Clique no botão `Create User` na página. Iremos ser levados para a página de login,
caso não tenha se identificado antes. Após o login, vemos um formulário que nos
permite adicionar um novo usuário. Preencha o formulário e clique no botão `Create`.
Se houver qualquer erro de entrada, um aviso de erro vai aparecer e não poderemos
salvar a entrada. Voltando à página da lista dos usuários, devemos ver o recém
adicionado usuário.

Repita os passos acima para adicionar mais usuários. Observe que a página da
lista de usuários automaticamente pagina os usuários, caso exista muitos a serem
exibidos em uma página.

Se você entrar como um administrador usando `admin/admin`, podemos ver a página
do administrador com a seguinte URL:

~~~
http://hostname/testdrive/index.php?r=user/admin
~~~

Isso irá nos mostrar as entradas de usuário em um formato tabular agradável.
Podemos clicar sobre as células do cabeçalho para ordenar as colunas correspondentes.
Podemos clicar nos botões em cada linha de dados para ver, atualizar ou excluir a linha
correspondente. Nós podemos navegar em páginas diferentes. Nós também podemos filtrar e
pesquisar os dados em que estamos interessados.

Todas essas interessantes características foram criadas sem escrever uma única linha de código!

![Página do administrador](first-app6.png)

![Página para criar um novo usuário](first-app7.png)

<div class="revision">$Id: quickstart.first-app.txt 1264 2009-07-21 19:34:55Z qiang.xue $</div>
